Motivation and Context

By default, the DynamoDbEnhancedClient does not natively support storing multiple Java subclasses of a common supertype in the same table. In complex domain models (e.g. storing both Employee and Customer instances of Person), there was a need to write complex type‐discrimination logic. This change introduces a clean, annotation‐driven layer that automatically dispatches to the correct subtype schema at runtime, reducing boilerplate and eliminating fragile manual checks.

Modifications

• New Annotations
  • @DynamoDbSubtypeDiscriminator to mark the discriminator field on the base type.
  • @DynamoDbSupertype (with inner Subtype annotation) to declare each concrete subtype and its discriminator value on the supertype class.
• Static Attribute Tag
  • Added StaticAttributeTags.subtypeName() and SubtypeNameTag to record the discriminator attribute name in TableMetadata.
• Polymorphic Schema Classes
  • StaticSubtype<T> encapsulates a subtype’s TableSchema and its discriminator value.
  • StaticPolymorphicTableSchema<T> implements TableSchema<T>: reads the discriminator from the item or object, looks up the right StaticSubtype, and delegates all mapping calls.
  • PolymorphicTableSchema<T> wraps the static polymorphic schema for recursive resolution and caching.
• Factory Integration
  • Updated TableSchemaFactory.fromClass(...) to detect @DynamoDbSupertype and route to PolymorphicTableSchema.create(...).
• Extension & Operation Hooks
  • Modified EnhancedClientUtils.readAndTransformSingleItem and all core operations (Put, Update, Transact) to resolve and use the concrete subtype schema before invoking extensions or building requests.
• Converters Delegation
  • Added an override of converterForAttribute(...) in StaticPolymorphicTableSchema to delegate to the root schema so user‐defined @DynamoDbConvertedBy converters continue to work seamlessly.
• Diagrams & Documentation
  • Added a Low Level Design document including sequence diagrams and flowcharts to illustrate routing logic and serialization/deserialization flows.

Testing

• Unit Tests
  • Added tests for StaticPolymorphicTableSchema covering:
    • Mapping to and from each subtype (mapToItem / itemToMap).
    • Error cases: missing discriminator, invalid discriminator value, duplicate subtype names.
  • Verified that custom attribute converters (e.g. for Instant) are correctly applied via converterForAttribute.
• Integration Tests
  • Put/get/update items in a real DynamoDB Local table with a mixed set of Person and Customer subclasses.
  • Tested with polymorphic beans and flattened maps to ensure dispatch at each level.
• Manual Verification
  • Confirmed that client‐side extensions (e.g. auto‐timestamp update) receive the correct subtype schema context in beforeWrite / afterRead.

Screenshots (if appropriate)

(See design doc diagrams in Section 4 and 5 for visual routing and flowchart illustrations.)

Test Coverage Checklist

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the CONTRIBUTING document
• Local run of mvn install succeeds
• My code follows the code style of this project
• My change requires a change to the Javadoc documentation
• I have updated the Javadoc documentation accordingly
• I have added tests to cover my changes
• All new and existing tests passed
• I have added a changelog entry. Adding a new entry must be accomplished by running the scripts/new-change script and following the instructions.
• My change is to implement 1.11 parity feature and I have updated LaunchChangelog

License

• I confirm that this pull request can be released under the Apache 2.0 license